Import docs into repo and use ReadTheDocs #212
Conversation
Signed-off-by: Stefan Marr <[email protected]>
smarr
added
the
enhancement
docs/csp-design.md
Outdated
|
|
||
| One possible way for modeling concurrent systems is Tony Hoare's classic approach of having isolated processes communicate via channels, which is called [Communicating Sequential Processes (CSP)](https://en.wikipedia.org/wiki/Communicating_sequential_processes). Today, we see the approach used for instance in [Go](https://blog.golang.org/share-memory-by-communicating) and [Clojure](http://clojure.com/blog/2013/06/28/clojure-core-async-channels.html). | ||
|
|
||
| While [Newspeak's specification](http://bracha.org/newspeak-spec.pdf) and implementation come with support for Actors, I want to experiment also with other abstractions, and CSP happens to be an interesting one, since it models systems with blocking synchronization, also know as channels with rendezvous semantics. I am not saying CSP is better in any specific case than actors. Instead, I want to find out where CSP's abstractions provide a tangible benefit. |
docs/csp-design.md
Outdated
|
|
||
| While [Newspeak's specification](http://bracha.org/newspeak-spec.pdf) and implementation come with support for Actors, I want to experiment also with other abstractions, and CSP happens to be an interesting one, since it models systems with blocking synchronization, also know as channels with rendezvous semantics. I am not saying CSP is better in any specific case than actors. Instead, I want to find out where CSP's abstractions provide a tangible benefit. | ||
|
|
||
| But, the reason for this post is another one. One of my biggest quibbles with most CSP implementations is that they don't take isolation serious. Usually, they provide merely lightweight concurrency and channels, but they rarely ensure that different processes don't share any mutable memory. So, the door for low-level race conditions is wide open. The standard argument of language or library implementers is that guaranteeing isolation is not worth the performance overhead that comes with it. For me, concurrency is hard enough, so, I prefer to have the guarantee of proper isolation. Of course, another part of the argument is that you might need shared memory for some problems, but, I think we got [a more disciplined approach for those problems](http://stefan-marr.de/2016/02/domains-sharing-state-in-the-communicating-event-loop-actor-model/), too. |
There was a problem hiding this comment.
merely provide lightweight
docs/csp-design.md
Outdated
|
|
||
| Ok, so how can we realize isolated processes in Newspeak? As it turns out, it is pretty simple. Newspeak already got the notion of _values_. Values are deeply immutable objects. This means values can only contain values themselves, which as a consequence means, if you receive some value from a concurrent entity, you are guaranteed that the state never changes. | ||
|
|
||
| In [SOMns](https://github.com/smarr/SOMns), you can use the [`Value`](https://github.com/smarr/SOMns/blob/master/core-lib/Kernel.som#L82) mixin to mark a class as having value semantics. This means that none of the fields of the object are allowed to be mutable, and that we need to check that fields are only initialized with values in the object's constructor. Since Newspeak uses nested classes pretty much everywhere, we also need to check that the outer scope of a value class does not have any mutable state. Once that is verified, an object can be a proper deeply immutable value, and can be shared with out introducing any data races between concurrent entities. |
docs/csp-design.md
Outdated
|
|
||
| ## Channels | ||
|
|
||
| The other aspect we need to think about is how can we design channels so that they preserve isolation. As a first step, I'll only allow to send values on the channel. This ensure isolation and is a simple efficient check whether the provided object is a value. |
There was a problem hiding this comment.
This ensures isolation .... simple and efficient check, ...
docs/launcher.md
Outdated
| Below, we see that `./som --help` supports a large set of options, of which we | ||
| detail only a few. | ||
|
|
||
| The basic options include `-d` to allow to attach a Java debugger, for instance |
There was a problem hiding this comment.
to allow attachment of a Java debugger
|
Thanks for the review. I fixed most of the things. For Files, and HTTP etc, well, ideally, some documentation would be provided as part of the modules themselves. These design notes are probably more useful if they talk about general design considerations and aspects that are somewhat outside of the scope of documentation for a module itself. I don't have any concrete plans at the moment. I'd say this is somewhat a on-demand thing. |
|
The documents are well organized and easy to follow, it's a good start and probably enough for a beginner getting started with SOMns. If I were to want to anything else, as a person without previous VM experience, it would be a narrative of how the different nodes work together. For one example, a brief explanation of how the dispatch nodes are invoked following the invocation of MessageSendNode. Ideally, the narrative would describe how nodes work together with respect to how they are organized in the repository. I think this would be most helpful for beginners looking through the different modules of SOMns - those that contain the node themselves, the node factories, the mixin and method builders, and so on. |
|
@Richard-Roberts ok, thanks. Well, I'd be happy to review anything you'd write! :D |
- update docs and remove non-standard html - added mkdocs.yml config - moved release check list - restructure and breakup docs - added CSP design notes Signed-off-by: Stefan Marr <[email protected]>
Signed-off-by: Stefan Marr <[email protected]>
Signed-off-by: Stefan Marr <[email protected]>
|
@smarr I think you mean rewrite anything I'd write, but sure I'll have a go sometime this week! |
The documentation was previously stored on http://som-st.github.io/somns/.
This PR moves it here to make it easier to maintain.
Furthermore, I enabled ReadTheDocs rendering for the
/docs/folder.The docs are readable at: http://somns.readthedocs.io/
@daumayr @Richard-Roberts, would be great if you could give it a brief look.
I hope this is going to be useful for new students, which I expect to start in a few month.